Object management functions
This section describes PKCS#11 object management functions.
C_CreateObject
This function operates as specified in PKCS#11 with the following exceptions:
If the security mode NoClearPINs is enabled, the host library version of the function will encrypt the template before submitting it to the module and the module function will verify the data was encrypted.
If the object is of type CKO_PUBLIC_KEY
, CKO_PRIVATE_KEY
, CKO_CERTIFICATE
or CKO_CERTIFICATE_REQUEST
and the key type is CKK_RSA
or CKK_DSA
, the key is checked for validity.
Synopsis
C_CreateObject(
CK_SESSION_HANDLE hSession,
CK_ATTRIBUTE_PTR pTemplate,
CK_ULONG ulCount,
CK_OBJECT_HANDLE_PTR phObject
);
C_CopyObject
This function operates as specified in PKCS#11. except that if the base object has a valid CKA_USAGE_LIMIT attribute then the base object is deleted after a successful copy.
Note
If the “Increased Security” flag is set as part of the security policy, then C_CopyObject does not allow changing the CKA_MODIFIABLE flag from FALSE to TRUE.
Synopsis
C_CopyObject(
CK_SESSION_HANDLE hSession,
CK_OBJECT_HANDLE hObject,
CK_ATTRIBUTE_PTR pTemplate,
CK_ULONG ulCount,
CK_OBJECT_HANDLE_PTR phNewObject
);
Operation in WLD Mode
When ProtectToolkit is configured to operate in WLD mode, this function is not supported and will return the error CKR_FUNCTION_NOT_SUPPORTED.
CT_CopyObject
This function is a SafeNet extension to PKCS#11. It is identical to the C_CopyObject function, except it is capable of copying objects from one token to another token where the two tokens belong to the same adapter.
Note
This function can only be used to copy objects whose attribute CKA_EXTRACTABLE=TRUE.
This function copies an object from one session to another session, creating a new object for the copy.
-
hSourceSession is the source session’s handle;
-
hDestSession is the destination’s session handle;
-
hObject is the object’s handle;
-
pTemplate points to the template for the new object;
-
ulCount is the number of attributes in the template;
-
phNewObject points to the location that receives the handle for the copy of the object.
Synopsis
CT_CopyObject(
CK_SESSION_HANDLE hDestSession,
CK_SESSION_HANDLE hSourceSession,
CK_OBJECT_HANDLE hObject,
CK_ATTRIBUTE_PTR pTemplate,
CK_ULONG ulCount,
CK_OBJECT_HANDLE_PTR phNewObject
);
If the base object has a valid CKA_USAGE_LIMIT attribute, then the base object is deleted after a successful copy.
The template may specify new values for any attributes of the object that can ordinarily be modified (for example: in the course of copying a secret key, a key’s CKA_EXTRACTABLE attribute can be changed from TRUE to FALSE, but not the other way around. If this change is made, the new key’s CKA_NEVER_EXTRACTABLE attribute will have the value FALSE.
Similarly, the template may specify that the new key’s CKA_SENSITIVE attribute be TRUE; the new key will have the same value for its CKA_ALWAYS_SENSITIVE attribute as the original key). It may also specify new values of the CKA_TOKEN and CKA_PRIVATE attributes (for example, to copy a session object to a token object).
If the template specifies a value of an attribute which is incompatible with other existing attributes of the object, the call fails with the return code CKR_TEMPLATE_INCONSISTENT
.
If a call to CT_CopyObject cannot support the precise template supplied to it, it will fail and return without creating any object.
Only session objects can be created during a read-only session. Only public objects can be created unless the normal user is logged on.
Note
If the “Increased Security” flag is set as part of the security policy, then C_CopyObject does not allow changing the CKA_MODIFIABLE flag from FALSE to TRUE.
C_DestroyObject
This function operates as specified in PKCS#11.
If the object has the optional attribute CKA_DELETABLE
set to FALSE the object cannot be deleted with this function and CKR_OBJECT_READ_ONLY
is returned.
Synopsis
C_DestroyObject(
CK_SESSION_HANDLE hSession,
CK_OBJECT_HANDLE hObject
);
C_GetObjectSize
This function operates as specified in PKCS#11.
ProtectToolkit-C interprets the object size to be the amount of memory guaranteed to be sufficient to encode the object’s attributes.
Synopsis
C_GetObjectSize(
CK_SESSION_HANDLE hSession,
CK_OBJECT_HANDLE hObject,
CK_ULONG_PTR pulSize
);
C_GetAttributeValue
This function operates as specified in PKCS#11 with the following extensions. With ProtectToolkit-C it is possible to enumerate through all attributes for a given object. This extension is supported as follows.
Synopsis
C_GetAttributeValue(
CK_SESSION_HANDLE hSession,
CK_OBJECT_HANDLE hObject,
CK_ATTRIBUTE_PTR pTemplate,
CK_ULONG ulCount
);
The first call C_GetAttributeValue operates as follows to initialize the enumeration.
CK_ATTRIBUTE at;
rv = C_GetAttributeValue(hSession, hObject, &at, 0);
Then, to get all the attributes, loop as follows:
for (;;) {
at.type = CKA_ENUM_ATTRIBUTE;
at.pValue = 0;
rv = C_GetAttributeValue(hSession, hObject, &at, 1);
if ( rv == CKR_ATTRIBUTE_TYPE_INVALID )
break; /* got all the attributes */
}
Sensitive attributes are returned with the type and length information but an empty value, and also return a result value of CKR_ATTRIBUTE_SENSITIVE. On implementations where this extension is not supported, the calls to C_GetAttributeType are likely to fail with the CKR_ATTRIBUTE_TYPE_INVALID error code.
With a result code of CKR_OK or CKR_ATTRIBUTE_SENSITIVE, the CK_ATTRIBUTE structure has the type and valueLen fields set appropriately for the next attribute, however the pValuefield will be NULL_PTR. To retrieve the actual value of the attribute, it is necessary to allocate the required room for the value and then make a second call to C_GetAttributeValue.
Special processing or access checks can be made if the object is a Hardware Feature. See Hardware Feature Objects.
C_SetAttributeValue
This function operates as specified in PKCS#11.
Special processing or access checks can be made if the object is a Hardware Feature. See Hardware Feature Objects.
Synopsis
C_SetAttributeValue(
CK_SESSION_HANDLE hSession,
CK_OBJECT_HANDLE hObject,
CK_ATTRIBUTE_PTR pTemplate,
CK_ULONG ulCount
);
C_FindObjectsInit
This function operates as specified in PKCS#11 with the following exception:
PKCS#11 states that to match CKO_HW_FEATURE
objects this class must be specified in the supplied template. ProtectToolkit-C does not enforce this requirement.
Synopsis
C_FindObjectsInit(
CK_SESSION_HANDLE hSession,
CK_ATTRIBUTE_PTR pTemplate,
CK_ULONG ulCount
);
C_FindObjects
This function operates as specified in PKCS#11.
Synopsis
C_FindObjects(CK_SESSION_HANDLE hSession,
CK_OBJECT_HANDLE_PTR phObject,
CK_ULONG ulMaxObjectCount,
CK_ULONG_PTR pulObjectCount
);
C_FindObjectsFinal
This function operates as specified in PKCS#11.
Synopsis
C_FindObjectsFinal(
CK_SESSION_HANDLE hSession
);